<!DOCTYPE html>
<html>
<head>
<link rel="Stylesheet" type="text/css" href="style.css">
<title>smart pointers and interior mutability</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>

<div id="smart pointer"><h1 id="smart pointer" class="header"><a href="#smart pointer">smart pointer</a></h1></div>
<p>
Rust use RAII manage resources like C++. Rust provide three type of smart pointer: <code>Box</code>(unique semantics), <code>Ac</code>/<code>Arc</code>(shared semantics), <code>Weak</code>(auxiliary utility of Ac/Arc). The corresponding utilities in C++ are <code>unique_ptr</code>, <code>shared_ptr</code>, <code>weak_ptr</code>. The semantics of Rust smart pointer and C++ smart pointer is identical, except that Rust introduce interior mutability due to the restriction of Rust reference rules.
</p>

<p>
Smart pointers are designed as substitute of raw pointer, so in most cases, we can use smart pointer as raw pointer. The API of smart pointers focus on the <span id="smart pointer-interaction"></span><strong id="interaction">interaction</strong> with raw pointer(such as how to get smart pointer from raw pointer) and the <span id="smart pointer-status"></span><strong id="status">status</strong> of smart pointer(such as how number strong references point to the same object).
</p>

<p>
For the sake of safety, Rust don't provide C++ style constructor such as <code>shared_ptr(T * const ptr)</code>, rather than allocate resources from smart pointer directly, resemble factory function <code>make_shared&lt;T&gt;(args...)</code> in C++.
</p>

<div id="smart pointer-common operations"><h2 id="common operations" class="header"><a href="#smart pointer-common operations">common operations</a></h2></div>
<p>
Conversion between raw pointer and smart pointer: <code>frow_raw()</code>,<code> into_raw()</code> and <code>as_ptr()</code>
</p>



<p>
Downcast the general smart pointer(such as <code>Box&lt;dyn Any&gt;</code>) into concrete smart pointer:<code>downcast&lt;T&gt;(self)</code>
</p>


<div id="smart pointer-Box"><h2 id="Box" class="header"><a href="#smart pointer-Box">Box</a></h2></div>

<p>
Box play the roles of heap memory allocation utility like <code>malloc()</code> in C and unique ownership smart pointer of item.
</p>

<p>
<code>leak()</code>
</p>



<div id="smart pointer-Rc and Arc"><h2 id="Rc and Arc" class="header"><a href="#smart pointer-Rc and Arc">Rc and Arc</a></h2></div>

<div id="smart pointer-Rc and Arc-Get the ownership of mutable reference of inner value of Rc."><h3 id="Get the ownership of mutable reference of inner value of Rc." class="header"><a href="#smart pointer-Rc and Arc-Get the ownership of mutable reference of inner value of Rc.">Get the ownership of mutable reference of inner value of Rc.</a></h3></div>

<p>
<code>get_mut()</code>
</p>

<p>
<code>make_mut()</code>
</p>

<p>
<code>try_unwrap(self)</code>: will consume Arc and convert it into inner value.
</p>

<p>
I can't understands the purpose of <code>make_mut()</code>.
</p>
<pre rust>
use std::rc::Rc;

let x = Rc::new("hello".to_owned());
let x_ptr = Rc::into_raw(x);

unsafe {
    // Convert back to an `Rc` to prevent leak.
    let x = Rc::from_raw(x_ptr);
    assert_eq!(&amp;*x, "hello");

    // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe.
}

// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!
</pre>

<div id="smart pointer-Rc and Arc-status of Rc"><h3 id="status of Rc" class="header"><a href="#smart pointer-Rc and Arc-status of Rc">status of Rc</a></h3></div>

<div id="smart pointer-Rc and Arc-Arc"><h3 id="Arc" class="header"><a href="#smart pointer-Rc and Arc-Arc">Arc</a></h3></div>


<div id="smart pointer-Weak"><h2 id="Weak" class="header"><a href="#smart pointer-Weak">Weak</a></h2></div>
<p>
Weak is just a auxiliary utility for Ac, breaking the circumstance of  cycle-reference. The only way of using Weak is that <span id="smart pointer-Weak-upgrade it into Rc temporarily"></span><strong id="upgrade it into Rc temporarily">upgrade it into Rc temporarily</strong>.
</p>

<div id="interior mutability"><h1 id="interior mutability" class="header"><a href="#interior mutability">interior mutability</a></h1></div>


<p>
Both Cell and RefCell <span id="interior mutability-hold the ownership"></span><strong id="hold the ownership">hold the ownership</strong> of inner value.
</p>

<div id="interior mutability-Cell"><h2 id="Cell" class="header"><a href="#interior mutability-Cell">Cell</a></h2></div>
<p>
The semantics of Cell is that a mutable memory location without reference counter. In most cases, we get a <span id="interior mutability-Cell-copy"></span><strong id="copy">copy</strong> of the inner value of Cell. 
</p>

<p>
<code>from_mut(&amp;mut T)</code>: Cell holds a mutable memory location, so it must insure the resource is mutable.
</p>

<div id="interior mutability-RefCell"><h2 id="RefCell" class="header"><a href="#interior mutability-RefCell">RefCell</a></h2></div>
<p>
The semantics of RefCell is that a mutable memory location with <span id="interior mutability-RefCell-runtime"></span><strong id="runtime">runtime</strong> reference counter and barrow rule. In most cases, we get a <span id="interior mutability-RefCell-reference"></span><strong id="reference">reference</strong> to the inner value of RefCell.
</p>

<p>
Strangely, The API of Cell and RefCell is not consistent.For instance, RefCell has a method <code>replace_with()</code> with receive a lambda and replace inner value with the value lambda returns, but Cell don't have this API(has the similar experimental function <code>update()</code>)
Another example, both RefCell and Cell has the same method <code>get_mut()</code>, but the semantics are different(The corresponding function of RefCell is <code>brrow_mut()</code>). 
</p>

<p>
RefCell don't have API <code>from_mut(&amp;mut T)</code> existing in  Cell.
</p>

<p>
It is worth noting that this two function is cautious or rarely-used.
</p>

<p>
<code>get_mut()</code>: The argument must be a <span id="interior mutability-RefCell-&amp;mut RefCell&lt;T&gt;"></span><strong id="&amp;mut RefCell&lt;T&gt;">&amp;mut RefCell&lt;T&gt;</strong>
</p>

<p>
<code>try_borrow_mut_unguarded()</code>: It is <span id="interior mutability-RefCell-unsafe"></span><strong id="unsafe">unsafe</strong>. The returned Result contains raw <span id="interior mutability-RefCell-&amp;T"></span><strong id="&amp;T">&amp;T</strong> not <span id="interior mutability-RefCell-Ref&lt;T&gt;"></span><strong id="Ref&lt;T&gt;">Ref&lt;T&gt;</strong>
</p>

</body>
</html>
